Implementing .NET Block interfaces

Implementing interfaces:

• IBlock

• IDiscreteSourceBlock

• Implementing IContinuousSourceBlock

• Implementing ISinkBlock

• Persistence

• CSense Sources

• Implementation Notes

• Deploying Assemblies

IBlock

This interface is required by the .NET Wrapper Block. This interface is used when your object takes input fields and generates output fields. The interface is defined as:

public interface IBlock

{

    UserControl GetConfigurationControl(InputFields inputFields);

    void Configure(InputFields inputFields, UserControl control);

    void UpdateOutputFields(InputFields inputFields, OutputFields outputFields);

    void CheckRunnability(InputFields inputFields, IRunnabilityResult result);

    void ExecutionStarted();

    void Execute(DateTime executeTime, InputValues inputs, OutputValues outputs);

    void ExecutionStopped();

}

IDiscreteSourceBlock

This interface is required by the Discrete .NET Wrapper Source Block. This interface is used when your object will be creating new output fields. The interface is defined as:

public interface ISourceBlock

{

    DateTime FirstExecuteTime { get; }

    bool IsAtEnd { get; }

    DateTime NextExecuteTime { get; }

}

public interface IDiscreteSourceBlock : ISourceBlock

{

    UserControl GetConfigurationControl();

    void Configure(UserControl control);

    void UpdateOutputFields(OutputFields outputFields);

    void CheckRunnability(IRunnabilityResult result);

    void ExecutionStarted();

    void Execute(DateTime executeTime, ref string index, OutputValues outputs);

    void ExecutionStopped();

}

NOTE: Remember to set the index string value on every call to the Execute method. This index value will be placed in the output port as the ‘Index’ field.

IContinuousSourceBlock

This interface is required by the Continuous .NET Wrapper Source Block. This interface is used when your object will be creating new output fields. The interface is defined as:

public interface ISourceBlock

{

    DateTime FirstExecuteTime { get; }

    bool IsAtEnd { get; }

    DateTime NextExecuteTime { get; }

}

public interface IContinuousSourceBlock : ISourceBlock

{

    UserControl GetConfigurationControl();

    void Configure(UserControl control);

    void UpdateOutputFields(OutputFields outputFields);

    void CheckRunnability(IRunnabilityResult result);

    void ExecutionStarted();

    void Execute(DateTime executeTime, OutputValues outputs);

    void ExecutionStopped();

}

ISinkBlock

This interface is required by the .NET Wrapper Sink Block. This interface is used when your object will only take input fields and not generate any outputs. The interface is defined as:

public interface ISinkBlock

{

    UserControl GetConfigurationControl(InputFields inputFields);

    void Configure(InputFields inputFields, UserControl control);

    void CheckRunnability(InputFields inputFields, IRunnabilityResult result);

    void ExecutionStarted();

    void Execute(DateTime executeTime, InputValues inputs);

    void ExecutionStopped();

}

Persistence

All classes must be marked with the Serializable attribute otherwise the object will not be persisted correctly. Also remember to mark all internal structs and classes with the Serializable attribute if they need to be persisted. Mark all variables that are not required for persistence with the NonSerialized attribute.

CSense Sources

The following interfaces and classes are specific to the .NET Wrapper Source blocks. They are only used if your object will use any of the CSense Sources.

• INeedCSenseSourceFactory: Interface that can be implemented by objects that implements any of the two source interfaces. This interface tells the .NET Wrapper Source block that your object requires the CSenseSourceFactory object.

• CSenseSourceFactory: Abstract class containing a list of all available sources that can be created along with the creation method that will create a required CSense Sources. This object is passed to your object through the INeedCSenseSourceFactory interface.

• CSenseSourceType: The CSense Source Type enumeration. The source type can either be discrete or continuous.

• ICSenseSource: Interface to a CSense Source that was created through the CSenseSourceFactory object.

• CSenseSourcePropertyType: Enumeration of CSense Source properties that can be set.

• CSenseProperty: The CSense Source property class holding the property type and the new value.

The .NET Wrapper Source blocks allows your object to use the CSense Source blocks internally. This is done by implementing the INeedCSenseSourceFactory interface. This interface only has one method:

public interface INeedCSenseSourceFactory

{

    void SetCSenseSourceFactory(CSenseSourceFactory factory);

}

This method is called when your object is instantiated, before any of the other methods are called. This allows your object to keep the factory as a member variable. (Remember to mark this member variable with the NonSerialized attribute).

This CSenseSourceFactory object can then be used by your object to list all possible sources this factory object can create for you. Sources are identified with a string. If you want to instantiate any of the CSense Sources, simply call the CreateSource method with the source name as input. This method instantiates the source and return the ICSenseSource interface. This interface is defined as:

public interface ICSenseSource

{

    string Name { get; }

    CSenseSourceType Type { get; }

    string Data { get; set; }

    InputFields Fields { get; }

    InputValues Values { get; }

    DateTime FirstExecuteTime { get; }

    bool IsAtEnd { get; }

    DateTime NextExecuteTime { get; }

    DialogResult Configure();

    bool Configure(List<CSenseProperty> values);

    bool CheckRunnability();

    List<string> RunnabilityWarnings { get; }

    List<string> RunnabilityErrors { get; }

    void ExecutionStarted();

    void Execute(DateTime executeTime);

    void ExecutionStopped();

}

General properties:

• Name: This property returns the CSense Source name, which is the same name you used to create the source via the CSenseSourceFactory object.

• Type: This property returns the CSense Source type. The type is either discrete or continuous.

• Data: This property is used for persistence. If you wish to save the CSense Source, just read the Data property and store the resulting string as a member variable in your class. When you wish to load a CSense Source, just set the Data property to this member variable string after you have created the CSense Source through the factory.

Design-time properties and methods:

• Fields: This property returns all the output fields from the source as input fields that you can use. This property will only return valid results after the block is configured.

• Configure: There are two configure methods. One shows the block's configuration dialog, while the other allows you to set certain properties on the source directly.

• • Dialog: This method shows the configuration dialog for the CSense Source. The method returns the dialog result which can either be OK or Cancel. Usually if this method returned OK, you will retrieve the Data property value from the source and store that value as a member variable in your class.

  • Property: This method takes a list of CSenseProperty objects. It will try to set these properties on the CSense Source. If it succeeded, then it will return true, otherwise some or all of the properties could not be set and it will return false. Currently only two properties can be set on some of the sources. They are:

  • • HistoryWindowStart: The start time of the history window

    • HistoryWindowEnd: The end time of the history window

• CheckRunnability: This method checks to see if the CSense Source is runnable. It will return true if runnable, else it will return false. After this method was called, you can read the RunnabilityWarnings and RunnabilityErrors properties. Remember that even if the source reported that it is runnable, it may still contain runnability warnings.

• RunnabilityWarnings: List of all the runnability warnings. This property should only be read after the CheckRunnability method was called.

• RunnabilityErrors: List of all the runnability errors. This property should only be read after the CheckRunnability method was called.

Run-time properties and methods:

• Values: This property returns all the field values as input values that you can use in your object. These values can only be read if the source is in execution mode. The source is considered to be in execution mode after the first call to the Execute method. When ExecutionStopped was called on the source, then the block is not in execution mode anymore.

• FirstExecuteTime: This property returns the first execute time of the source block. This property will be valid after the ExecutionStarted method was called.

• IsAtEnd: This property returns true if the source block is at the end of its data, otherwise it will return false. This property is also only valid after the ExecutionStarted method was called.

• NextExecuteTime: This property returns the next execution time. This property can be read after each execute.

• ExecutionStarted: This method must be called when the source is going to be executed. Usually, you will call this method in your ExecutionStarted method. This will also set the source into execution mode.

• Execute: This method will execute the source at the specified execute time. After this method is called, use the Values property to read the output fields of the source.

• ExecutionStopped: This method must be called when the source is going to be stopped.

NOTE: Only the classes specified can be serialized.

Implementation Notes

Inputs:

The InputFields and InputValues containers are read-only containers. You cannot modify these containers.

Outputs:

When adding fields to the OutputFields container, the following must be remembered:

• All field names must be valid field identifiers. This can be checked with the IsValidIdentifier static method on the Field class. It takes a string and returns true if it is a valid identifier, otherwise false. You can also make a string a valid identifier with the MakeValidIdentifier static method on the Field class.

• The OutputFields container must have fields with unique names. You may not add two fields with the same name to the container.

• Use the IsNameAllowed method on the OutputFields to see if the field name is allowed into the container. In the Discrete .NET Wrapper Source Block for instance, the name ‘Index’ may not be used as output field name because the Index field is automatically added to the output fields by the block itself.

• Use the IsTypeAllowed method on the OutputFields to see if the field type is allowed into the container. The Discrete .NET Wrapper Source Block for instance will not allow integer fields. The Continuous .NET Wrapper Source Block may only allow double fields if it is used within the Troubleshooter. The Continuous .NET Wrapper Source will allow all field types if it is used in the Architect.

The OutputValues container is a read-only container, but you may still change the timestamp, value and quality of the fields that is contained within the container. This OutputValues container will contain all the fields that you specified in the UpdateOutputFields method.

When changing output values on execute, the following must be remembered:

• If the value or quality of a field changes, the timestamp must change.

• The timestamp may only increase. It may never be less than the last timestamp you set on that field.

Runnability:

Your object is considered runnable unless you called the AddError method on the IRunnabilityResult interface supplied in the CheckRunnability method. The AddWarning method only adds warning messages, and will not mark your object as not runnable.

Deploying Assemblies

All class libraries are compiled into assembly DLL files. These class library files mist be placed in the application directory when used. In the case of Architect, if the object will be used in the Troubleshooters or Architect, it must be copied to the user specified install directory; by default:

---

Related topics:

• .NET Wrapper block

• .NET Wrapper Continuous source block

• .NET Wrapper Discrete source block

• .NET Wrapper sink block